MacOS X Developer Preview Release Notes Copyright © 2000 by Apple Computer, Inc. All Rights Reserved.
ProjectBuilderWO is what used to be called Project Builder in previous releases of Mac OS X Developer Preview and Mac OS X Server.
We now have a completely new integrated development environment that we are calling Project Builder in DP4. We encourage all developers other than WebObjects developers to shift to using that IDE. See the ProjectBuilder release notes for further information.
We will be working with the WebObjects team to design good integration between WebObjects Builder and the new Project Builder. For some period of time, though, ProjectBuilderWO will continue to be the primary IDE for use when developing WebObjects applications, so we will continue to ship ProjectBuilderWO with the WebObjects SDK until we have fully integrated WebObjects with the new Project Builder.
IMPORTANT NOTE: We do NOT plan to ship ProjectBuilderWO with the GM release of the Mac OS X SDK! If you feel that you have a compelling reason why we must continue to ship ProjectBuilderWO with the GM release of the Mac OS X SDK, please write to <macosx-tools-feedback@group.apple.com>. Otherwise, we plan to focus our efforts on improving the new Project Builder as rapidly as possible.
This section concentrates on some of the limitations of ProjectBuilderWO and its pb_makefiles-based build environment for the development of Carbon and Cocoa applications. Although Carbon and Cocoa applications can be developed using ProjectBuilderWO, it is going away and we strongly recommend shifting your projects into the new Project Builder. In most cases, the limitations listed below have already been fixed in the new Project Builder.
ProjectBuilderWO uses a BSD-based build environment based on 'make', shells, and other BSD tools. It has limitations derived from these historic roots. For example, avoid the use of spaces in the path name to your project, or in your file names. Also ensure that your path names do not contain characters that are interpreted in special ways by BSD shells, such as '\' (backslash), ':' (colon), ';' (semicolon), '&' (ampersand), '*' (asterisk), and carets '<' and '>'.
NOTE: The new Project Builder uses a new build tool called "jam" as the foundation of its build system, and that does allow us to properly handle spaces in path names, which we have been testing. We have not yet tested usage of those other special characters. But if you need to use spaces in path names, file names, or other aspects of your project, please shift to using the new Project Builder.
In addition, we do not recommend the use of standard HFS file systems for either your source code or build result directories. Extended HFS+ file systems should work fine, with the caveat that 'make install' (which is not typically done during development) will lose resource forks of a built Carbon application. To avoid that problem, we now recommend building Carbon applications with their resources stored into the data forks of separate files; see the section "Building Carbon Applications on HFS+ Volumes & General Resource Fork Issues" below for more information about that.
There have been some reports of Rez sometimes failing on UFS file systems when running as root.
For Cocoa and other non-Carbon development, either HFS+ or UFS should work fine.
When you create a new project, you now have the additional choice of "Carbon Application". For Carbon applications, please be sure to use this project type rather than "Application", or your project will not build properly. To create a subproject within a Carbon project, use the "Carbon Component" subproject type. The pb_makefiles have build support for Carbon applications. Consult the document "Using Project Builder to Build and Debug a Carbon Application" for more information.
ProjectBuilderWO does not currently directly support the creation of Carbon-based framework, library, and tool projects. This limitation has been addressed in the new Project Builder.
You can "import" projects into ProjectBuilderWO by using the New from Source... menu item in the Project menu. Again, if you are creating a Carbon project, please be sure to use Carbon Application and Carbon Component project types.
ProjectBuilderWO's build environment currently expects to build only a single Carbon resource file, called main.r. The main.r file must be put in the Resource Files bucket of your Carbon Application project. If you have multiple resource files, you can include them from main.r. They must be in the same directory as your main.r file, and must also be in the Resource Files bucket at the top level of your project.
When building your Carbon application, if Rez fails due to a syntax error in a .r file you may need to manually remove the main.rsrc file from your <app>.build/objects-optimized directory.
NOTE: The new Project Builder allows the use of multiple .r and .rsrc files as source files in your Carbon projects.
Mac OS X is moving to a new application packaging structure for all applications, both Carbon and Cocoa. The new application package structure is outlined in the CFBundle/CFPlugIn release notes. The old structure will continue to work, but it is recommended that you convert your application to the new structure as it is the format NSBundle first checks for when looking for resources. (NOTE: The application packaging has changed between Developer Preview 2 and Developer Preview 3 as well.)
In DP3, on "make install," the ProjectBuilderWO makefiles will still create an old-style package. However, you can add the following to your Makefile.preamble to cause the new style package to be built:
BUNDLE_STYLE = MACOSX
This will cause the script /System/Developer/Makefiles/pb_makefiles/convertBundle to be run at the end of "make install" to convert your application's app package to the new style. Note that if you run "make install" as yourself and not as root, this script might fail.
If your application package needs to work on MacOS X Server, or you have some code that rummages through the application wrapper without going through NSBundle or CFBundle APIs, you might not be able to switch to the new format immediately.
NOTE: The new Project Builder directly builds the new style of application packages, with no special flags needed.
In Developer Preview 3, Finder prefers application and document icons in the ICNS format. For more information on how to convert TIFF icons to ICNS format, please refer to the AppKit release notes.
In addition to the new application packaging structure, there are new mechanisms for storing information such as an application's type and creator, and the document types which it can view and edit.
To specify this information, you should create a CustomInfo.plist file for your project, as described in the InfoPlist.html release note. Although in the future the primary format of these files will be XML, it is easier at this point to create an old-style plist file. See /System/Developer/Examples/AppKit/Sketch/CustomInfo.plist for an example.
When you add the "BUNDLE_STYLE = MACOSX" flag to your project as described above, the convertBundle script also converts the CustomInfo.plist file into the appropriate new format of the Info.plist file.
When you add a new-style CustomInfo.plist file to your project to specify this information, you should remove any App Icon and Document Icons information from the Project Attributes inspector in ProjectBuilderWO's Project Inspector panel for your project.
For Carbon applications on Mac OS X, Apple recommends storing Carbon Resource Manager resources in the data fork of a separate file in the application wrapper.
The HFS+ file system supports resource forks on Mac OS X, but, in general, the Unix command line utilities do not properly deal with resource forks. Because the ProjectBuilderWO build system is based on command line tools, this can cause problems when building Carbon projects that include or generate files with resource forks.
The only known problem with the makefiles for building typical Carbon applications occurs when you build the "install" target. The install target copies the built application from your build directory to its installed location using a tool called "gnutar" which will lose any resource forks as it copies the application. The install target also runs "strip" on the application executable which will also cause the resource fork to disappear.
To avoid these problems, we now recommend using a new flag to cause ProjectBuilderWO to write Carbon resources into the data fork of a separate file in the application package. To do this, ProjectBuilderWO's pb_makefiles take advantage of a new "-useDF" argument to Rez.
To enable building resource data into a data file, put the following in your Makefile.preamble:
USE_DATA_FORK_FOR_RESOURCES=YES
NOTE: The new Project Builder generates resources into data forks by default.
In some cases, you must enter a carriage return to signal the
end of editing in text fields in ProjectBuilderWO's Inspector or
Preferences panels.
When doing a build after modifying one or more header files, you may find that ProjectBuilderWO does not build everything you expected. In such cases, first do a build 'clean' then a full build.
NOTE: The new Project Builder automatically does proper analysis of header file dependencies for incremental builds.
ProjectBuilderWO's source code indexing does not yet support
C++, so features that depend on that (project-wide Find
Definitions and Find References, and the Class Browser) are not
available for C++ source code. Project-wide textual find can be
used.
To build a project (for example, a tool) that uses standard C++ features such as cin / cout, you must add the stdc++ library to your project. To do this, double-click the Library suitcase name in your project and add the /usr/lib/libstdc++ library.
The following features were new in the Mac OS X Developer Preview 1 release:
ProjectBuilderWO now integrates source code views into the build, find, and debug panels. In addition, the stack display has also been integrated into the debug panel. When you select a build warning or error message, or a find result, or a stack frame, the appropriate file is displayed in the tool's source code view. You can edit the code in the source code view, or set, move, and remove breakpoints there when debugging. (Note that, as usual when setting breakpoints in ProjectBuilderWO, you need to double-click in the margin view along the left side of the source code view.)
Resizing a tool's source code view to less than one line of text, or double-clicking on a result, will disable in-tool editing and instead edit the file either in the project window or in a standalone window, depending on your preference settings.
Running and debugging now use separate interfaces; both use a terminal-like view but the debugger adds a stack view and a text view.
On some rare occasions, it may appear that one of the views of one of these tools has disappeared. In such cases, try clicking the mouse in grey regions (the split bar) at the top or bottom of the window and moving them up or down.
If you have listed frameworks in a project's Frameworks suitcase, and you have the source code for those frameworks, you can set things up to allow you to directly navigate into the framework project from the Frameworks suitcase of your original project. In some cases, though, this may not be what you want, and you may need to explicitly point at the framework that you do want to use with your project.
To view and edit the search path for frameworks, select the "Search Paths" pane in the Preferences panel and configure it appropriately. This modifies the NSProjectSearchPath default. Once this default has been set, ProjectBuilderWO will use it to search for project directories that correspond to the frameworks listed in a Project's Frameworks suitcase. When it finds a project, it will display its list of suitcases in the file browser in place of the Headers, PrivateHeaders and Documentation of a deployed framework.
In addition, by default ProjectBuilderWO also looks for framework projects in the directory which contains your project. To prevent this, you may need to explicitly specify the framework that you want to reference, as described below, or even move undesired framework projects to a different directory.
It is also possible to directly set the project that ProjectBuilderWO will load for a framework. To do this, select a framework and bring up the file inspector. Select the "Specify Path" button. This will display a combo box with a list of all the projects and deployed frameworks which may correspond to the inspected framework. You can either select a path from this list, type in a new path or hit the "Browse" button to search for a framework in the open panel. Once you have specified a new path, hit "Apply" and the browser will display the project to the right of the framework name.
ProjectBuilderWO has also added a few conveniences which take advantage of this new feature. If a framework is displaying a project, you can double-click on the framework name to open the framework's project in a new window. The Project Find panel allows you to broaden its search scope to include all frameworks, either deployed or project-based. Simply select "Project & Frameworks" from the search scope popup list. Selecting "Selected Project Only" will restrict the search to the current project and its subprojects.
Finally, the build panel allows the user to build framework dependencies before building the main project. To enable this, raise the Build Options panel and select the "Build Frameworks" button.